Open API Reference UI usage

After you subscribe to an API from the API Catalog, use the REST tab to browse the OpenAPI Reference UI for the REST endpoints for the API. The UI also includes the associated parameters and responses for the API.

note

You can deploy each API REST endpoint to a different environment. If you deploy the process that contains the API in a Web Services Server listener to a different environment than the API component, the Web Services Server listener information is unknown. However, the API owner can overwrite the endpoint definition and outputs for use in the Developer Portal's REST endpoints. When the API owner overwrites the endpoint definition, the overwrite takes effect, regardless of what environment the overwrite is on.

Servers

The base URL for the API.

note

servers replaces the host, basePath, and schemes keywords used in OpenAPI 2.0.

Authorize

When the Authorize button displays a closed lock, the API is properly configured and authorizations are pre-populated in the portal. Clicking the Authorize button opens a panel that describes the type of authorization currently associated with the API.

Selecting Logout clears the Authentication Token and allows you to enter different credentials in order to explore and alter values. Logging out disables the Try It Out and Execution buttons until proper credentials are re-entered.

Based on the Authentication Type set for the API in the Authentication column of the Configure APIs and Applications > Deployed APIs page API Management, you need the following credentials to log back in:

• Basic authentication requires a user name and password.
• External Provider authentication requires OAuth 2.0 client_id and client_secret credentials. If the client_id is not auto-populated, enter the external authentication GUID (the alphanumeric string after components= in your URL) followed by :OPENID in the client_id field. Leave the Client Secret field blank, and click Authorize. Then, you are taken to the identity provider sign in screen if you are not already signed in.

note

When authentication is not set, the Authorize feature does not show.

Default tags

In the default section of the OpenAPI Reference UI, the Try It Out button allows you to test, edit, and re-test your API to experiment with various call mechanisms of your API.

The Developer Portal has limited support for JWT authentication for the “Try it out” feature, and by default uses Proof Key for Code Exchange (PKCE) Authorization Code flow with openid scope for JWT authentication.

note

The Developer Portal uses an access token to execute APIs. Some identity providers, such as Google and Microsoft Azure, issue opaque access tokens. The API Gateway does not support opaque access tokens, so you cannot test APIs that use identity providers issuing opaque tokens from the Developer Portal.

The responses associated with an API are dependent on the resource path and HTTP method set in the REST endpoint. Currently, the OpenAPI UI supports GET, POST, UPDATE, and DELETE.

Three elements display as a result of executing an API in the OpenAPI Reference UI. Clicking Try It Out for a POST response allows you to edit the example value to call various features. The portal displays a detailed list of potential code response errors.

note

Information produced in the OpenAPI reference UI is not retained when you exit the REST tab.